2025年9月23日中文

一份关于使用环境变量管理 Python 应用程序配置的全面指南。学习在不同环境中实现安全性、可移植性和可伸缩性的最佳实践。

Python 配置管理：精通环境变量以应对全球化应用

在当今动态的软件开发环境中，有效的配置管理至关重要。对于部署在从本地开发到跨洲生产服务器的各种环境中的 Python 应用程序而言，这一点尤为突出。环境变量提供了一种健壮、安全且可移植的解决方案，用于管理应用程序设置，而无需在代码中硬编码敏感信息或直接修改应用程序代码。本指南全面概述了如何在 Python 中使用环境变量，涵盖了适用于全球化应用的最佳实践、安全注意事项和高级技术。

为什么要使用环境变量？

环境变量是动态命名的值，可以影响计算机上运行进程的行为方式。它们是任何操作系统不可或缺的一部分，并为 Python 应用程序配置提供了几个关键优势：

安全性： 避免将敏感信息（如 API 密钥、数据库密码和加密密钥）直接硬编码到您的代码中。环境变量允许您将这些凭据安全地存储在代码库之外。
可移植性： 无需修改代码即可轻松将您的应用程序部署到不同环境（开发、测试、预发布、生产）。只需相应地调整环境变量即可。
可伸缩性： 管理应用程序在不同服务器或容器上的多个实例的配置。每个实例都可以拥有自己独特的环境变量集。
配置管理： 集中管理应用程序设置，从而更容易跟踪更改并恢复到以前的配置。
开发工作流： 不同的开发人员可以使用不同的环境，而不会影响彼此的代码。

在 Python 中访问环境变量

Python 提供了几种访问环境变量的方法。最常见的方法是使用 os 模块。

使用 `os` 模块

os.environ 字典提供了对所有环境变量的访问。您可以使用变量名作为键来检索特定变量。

            import os

database_url = os.environ.get("DATABASE_URL")
api_key = os.environ.get("API_KEY")

if database_url:
    print(f"Database URL: {database_url}")
else:
    print("Database URL not found in environment variables.")

if api_key:
    print(f"API Key: {api_key}")
else:
    print("API Key not found in environment variables.")

重要提示： os.environ.get() 方法优于直接字典访问（os.environ['DATABASE_URL']），因为它在未找到变量时返回 None，从而防止 KeyError 异常。始终处理环境变量可能未设置的情况。

使用 `os.getenv()`

os.getenv() 是另一种访问环境变量的方法。它的行为类似于 os.environ.get()，但还允许您在未找到变量时指定一个默认值。

            import os

port = int(os.getenv("PORT", 5000))  # Default to 5000 if PORT is not set
host = os.getenv("HOST", "127.0.0.1") # Default to localhost if HOST is not set

print(f"Application running on {host}:{port}")

设置环境变量

设置环境变量的方法取决于您的操作系统和部署环境。

本地开发

在大多数操作系统上，您可以在终端会话中设置环境变量。这些变量仅在会话期间有效。

Linux/macOS

            export DATABASE_URL="postgresql://user:password@host:port/database"
export API_KEY="your_api_key"
python your_script.py

Windows

            set DATABASE_URL="postgresql://user:password@host:port/database"
set API_KEY="your_api_key"
python your_script.py

注意： 这些命令只为当前终端会话设置变量。当您关闭终端时，这些变量将丢失。要使它们持久化，您需要在您的 shell 配置文件（例如，Linux/macOS 的 .bashrc、.zshrc 或 Windows 的系统环境变量）中设置它们。

使用 `.env` 文件

对于本地开发，.env 文件是管理环境变量的便捷方式。这些文件是包含环境变量键值对的纯文本文件。切勿将 .env 文件提交到版本控制（例如 Git），尤其是当它们包含敏感信息时。

要使用 .env 文件，您需要安装 python-dotenv 包：

            pip install python-dotenv

在您的项目目录中创建一个名为 .env 的文件，格式如下：

            DATABASE_URL=postgresql://user:password@host:port/database
API_KEY=your_api_key
DEBUG=True

然后，在您的 Python 代码中，从 .env 文件加载环境变量：

            import os
from dotenv import load_dotenv

load_dotenv()

database_url = os.environ.get("DATABASE_URL")
api_key = os.environ.get("API_KEY")
debug = os.environ.get("DEBUG") == "True"

if database_url:
    print(f"Database URL: {database_url}")
else:
    print("Database URL not found in environment variables.")

if api_key:
    print(f"API Key: {api_key}")
else:
    print("API Key not found in environment variables.")

print(f"Debug Mode: {debug}")

部署环境

在部署环境（例如，云平台、容器编排系统）中，设置环境变量的方法因平台而异。

Docker 和 Docker Compose

使用 Docker 时，您可以在 Dockerfile 或 docker-compose.yml 文件中设置环境变量。

Dockerfile

            FROM python:3.9-slim-buster

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

ENV DATABASE_URL="postgresql://user:password@host:port/database"
ENV API_KEY="your_api_key"

CMD ["python", "your_script.py"]

docker-compose.yml

            version: "3.9"
services:
  web:
    build: .
    ports:
      - "5000:5000"
    environment:
      DATABASE_URL: "postgresql://user:password@host:port/database"
      API_KEY: "your_api_key"

Kubernetes

在 Kubernetes 中，您可以使用 ConfigMaps 或 Secrets 在 Pod 或 Deployment 配置中设置环境变量。

ConfigMap

            apiVersion: v1
kind: ConfigMap
metadata:
  name: my-config
data:
  DATABASE_URL: "postgresql://user:password@host:port/database"
  API_KEY: "your_api_key"

            apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-container
        image: my-image
        envFrom:
        - configMapRef:
            name: my-config

Secret

            apiVersion: v1
kind: Secret
metadata:
  name: my-secret
type: Opaque
data:
  DATABASE_URL: $(echo -n "postgresql://user:password@host:port/database" | base64)
  API_KEY: $(echo -n "your_api_key" | base64)

            apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-container
        image: my-image
        envFrom:
        - secretRef:
            name: my-secret

云平台 (AWS, Azure, Google Cloud)

大多数云平台都提供了为您的应用程序设置环境变量的机制。例如：

AWS： 使用 AWS Lambda 环境变量、EC2 实例元数据或 AWS Systems Manager Parameter Store。
Azure： 使用 Azure App Service 应用程序设置或 Azure Key Vault。
Google Cloud： 使用 Google Cloud Functions 环境变量、Google App Engine 环境变量或 Google Cloud Secret Manager。

有关详细说明，请参阅您所选云平台的具体文档。

环境变量管理的最佳实践

使用描述性名称： 选择能清楚表明其用途的环境变量名称（例如，DATABASE_URL 而不是 DB）。
避免硬编码： 切勿将敏感信息直接硬编码到您的代码中。
安全存储敏感信息： 使用秘密管理工具（例如 HashiCorp Vault、AWS Secrets Manager、Azure Key Vault、Google Cloud Secret Manager）来存储和管理敏感凭据。
不要提交 .env 文件： 始终将 .env 添加到您的 .gitignore 文件中，以防止意外将敏感信息提交到版本控制。
验证环境变量： 实施验证逻辑，以确保环境变量设置正确并具有预期值。
使用配置库： 考虑使用配置库（例如 Pydantic 的设置管理）来定义和验证您的应用程序配置。
考虑单一事实来源： 对于复杂的应用程序，考虑使用集中式配置服务器或服务来管理环境变量和其他配置设置。

安全注意事项

虽然环境变量提供了一种比硬编码更安全的配置管理方式，但了解其安全隐患并采取适当措施至关重要。

避免暴露环境变量： 小心不要在日志、错误消息或其他公共可访问的输出中暴露环境变量。
使用适当的访问控制： 限制对存储和管理环境变量的系统的访问。
加密敏感信息： 考虑对存储在环境变量中的敏感信息进行加密，尤其是在云环境中。
定期轮换凭据： 实施定期轮换敏感凭据（例如 API 密钥和数据库密码）的流程。
监控未经授权的访问： 监控您的系统是否存在对环境变量和配置设置的未经授权的访问。

高级技术

使用 Pydantic 进行配置验证

Pydantic 是一个数据验证和设置管理库，可以简化定义和验证应用程序配置的过程。

            from pydantic import BaseSettings

class Settings(BaseSettings):
    database_url: str
    api_key: str
    debug: bool = False

    class Config:
        env_file = ".env"  # Load from .env file

settings = Settings()

print(f"Database URL: {settings.database_url}")
print(f"API Key: {settings.api_key}")
print(f"Debug Mode: {settings.debug}")

Pydantic 自动加载环境变量，验证它们的类型，并提供默认值。它还支持从 .env 文件加载。

分层配置

对于复杂的应用程序，您可能需要管理分层配置设置。您可以通过使用环境变量前缀或使用支持分层配置的配置库来实现此目的。

使用前缀的示例：

            DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USER=user
DATABASE_PASSWORD=password
DATABASE_NAME=database

            import os

database_host = os.environ.get("DATABASE_HOST")
database_port = os.environ.get("DATABASE_PORT")
database_user = os.environ.get("DATABASE_USER")
database_password = os.environ.get("DATABASE_PASSWORD")
database_name = os.environ.get("DATABASE_NAME")


if database_host and database_port and database_user and database_password and database_name:
    database_url = f"postgresql://{database_user}:{database_password}@{database_host}:{database_port}/{database_name}"
    print(f"Database URL: {database_url}")
else:
    print("Database configuration incomplete.")

环境变量的全球化考量

在全球部署应用程序时，请考虑以下事项：

时区： 将时区信息存储为环境变量，以便在不同区域正确处理时间敏感的操作。例如，将 `TIMEZONE` 环境变量设置为 `Europe/London` 或 `America/Los_Angeles`。
本地化： 使用环境变量管理特定于区域设置的配置，例如日期和数字格式。
货币： 将货币代码存储为环境变量，以处理不同区域的金融交易。
区域 API 端点： 如果您的应用程序与具有区域端点的外部 API 交互，请使用环境变量为每个区域指定正确的端点。例如，`API_ENDPOINT_EU`、`API_ENDPOINT_US`、`API_ENDPOINT_ASIA`。
GDPR 和数据驻留： 请注意数据驻留要求，并使用环境变量配置您的应用程序，使其根据相关法规存储和处理数据。
翻译： 使用环境变量指定用户界面元素的语言，以支持多语言。

结论

环境变量是安全、可移植和可伸缩地管理 Python 应用程序配置的重要工具。通过遵循本指南中概述的最佳实践，您可以有效地管理应用程序在从本地开发到全球部署的各种环境中的配置。请记住优先考虑安全性，验证您的配置，并为您的特定需求选择正确的工具和技术。正确的配置管理对于构建健壮、可维护和安全的 Python 应用程序至关重要，这些应用程序可以在当今复杂的软件环境中蓬勃发展。